pp108 : XGrid (Objects)

XGrid (Objects)

The XGrid control can be used to construct multi-functional, high-performance grids (tables) to display data in tabular form. It enables display of large number of records from a database.

This control is derived from the AJAX Toolkit library - XGrid. For details about the control's behavior and functionality, see XGrid.

You can add controls to the XGrid control, which appear as columns in the table. The controls that can be inserted in an XGrid control are Check, Image, Input, List, Output, Password, Select, and Textarea.

Properties, Events, and Methods of the Control

The properties, events, and methods associated with the XGrid control define its behavior. You can set them either through the control's property sheet or programmatically using the APIs. For details, see XGrid.

The following XForms-related properties and methods are available for the control:

Table 1. List of Properties

Design-time property

Run-time property

Description

ID

Sets the string that identifies the control on an XForm. If not specified, a unique ID is automatically generated.

Class Name

className

Sets or retrieves the class name applied on the control.

Model

Sets the ID of the data model from which the data (specified using the Reference property) is displayed in the control. If model is not specified, it is inherited from the parent control's model.

Reference (xql)

Sets the location or expression for the XPath that contains the data (value) displayed in the control. The XPath refers to the child node or descendants of the immediate parent control's reference.

businessObject

Retrieves the root node of the XML data associated with the control. The location of the XML data is specified by the Reference property.

Shade Classes

Sets the classes you specify for displaying alternate rows in the XGrid. For example, light lightmedium.

Fixed Row Height

Sets a fixed height for rows in the XGrid.

Freezable Columns

Defines whether columns can be frozen.

Freezable Rows

Defines whether rows can be frozen.

Hidable Columns

Defines whether columns can be hidden.

Movable Columns

Defines whether columns can be moved.

Resizable Columns

Defines whether columns can be resized.

Sortable

Defines whether rows can be sorted.

Use Checkboxes

Defines whether the checkbox column in the XGrid can be hidden.

Use Row Cache

Sets the caching of row HTML to true.
Table 2. Attributes used for XGrid

Attribute

Property

Description

fixedRowHeight

n/a

Boolean with default value as true. If not specified, it is automatically set by the XGrid.
If you need to display images of variable height in rows, the XGrid must be enabled to show rows of variable heights. In such cases, you can set this attribute to False.
If all images have the same height (like composite images), you can set this attribute to True.
This will also increase the startup performance of XGrids that have large numbers of rows.

freezableColumns

n/a

Boolean with default value as true. Defines whether columns can be frozen.

freezableRows

n/a

Boolean with default value as true. Defines whether rows can be frozen.

hideableColumns

n/a

Boolean with default value as true. Defines whether columns can be hidden.

id

id

String; required, read only.Unique identifier of the XGrid.

movableColumns

n/a

Boolean with default value as true. Defines whether columns can be moved.

resizableColumns

n/a

Boolean with default value as true. Defines whether columns can be resized.

shadeClasses

shadeClasses

String that defines the classes to be used to shading the Xgrid. The classes must be separated by spaces. For example, shadeClasses='light lightmedium'.

sortable

n/a

Boolean with default value as true. Defines whether rows can be sorted.

useCheckboxes

n/a

Boolean with default value as true. Shows or hides the Checkbox column, which can be used to select multiple rows.

useRowCache

n/a

Boolean with default value as true. By default, the HTML of a row is cached, for optimal performance. This makes scrolling of large datasets smoother.
However, if you have a table that contains time dependent data, you might want to set this tofalse. For example, say when the data is older than 15 minutes, the cell should appear in red. An auto refresh of the data can handle this, but the row cache prevents the display of new data. In this situation, setuseRowCache=false.

Business Object

xpathBusinessObject

Required, read only. Sets the XPath from the rowData to the businessObject.

Reference

xpathRowData

Required, read only. Sets the XPath from the dataNode to the row data elements. The rowData, the top node of a row, is the repeating level in the XML data.
Table 3. List of Methods

Method

Description

addListener(sEventName, fpFunction)

Registers a function to an event, such that the function gets called when the event is fired on the control.

disable()

Disables the control on which it is invoked.

enable()

Enables the control on which it is invoked.

getBusinessObject()

Retrieves data or business object.

hide()

Hides controls and all associated child controls.

isEnabled()

Retrieves the value that denotes whether the control is enabled or not.

rebind(oBusinessObject)

Refreshes the controls (bound to a model) with data from the business object that is passed as a parameter. If no parameter is passed, the business object of the model's activeTuple node is used to refresh the control.

removeListener(sEventName, fpFunction)

Unregisters a function from an event, such that the function stops getting called when the event is fired on the control.

show()

Makes the control and its child controls visible.